import Details from '@/components/Details';

# Next.js plugin (`createNextIntlPlugin`)

When setting up `next-intl` for the [App Router](/docs/getting-started/app-router), you'll add `next-intl/plugin` to your Next.js config.

At the minimum, it will look like this:

```tsx filename="next.config.ts"
import {NextConfig} from 'next';
import createNextIntlPlugin from 'next-intl/plugin';

const nextConfig: NextConfig = {};

const withNextIntl = createNextIntlPlugin();
export default withNextIntl(nextConfig);
```

For customization, you can provide options to the plugin.

## `requestConfig` [#request-config]

By default, `next-intl` will look for a file called [`i18n/request.ts`](/docs/usage/configuration#server-client-components) which returns request-specific configuration. This file is searched for both in the `src` folder as well as in the project root with the extensions `.ts`, `.tsx`, `.js` and `.jsx`.

If you prefer to move this file somewhere else, you can provide a path to the plugin:

```tsx filename="next.config.ts"
const withNextIntl = createNextIntlPlugin(
  // Specify a custom path here
  './somewhere/else/request.ts'
);
```

Or if you're combining this with other options, you can use the `requestConfig` option:

```tsx filename="next.config.ts"
const withNextIntl = createNextIntlPlugin({
  requestConfig: './somewhere/else/request.ts'
});
```

## `experimental`

For early adopters, the Next.js plugin provides various experimental options that let you try out new features before they're released as stable.

### `createMessagesDeclaration` [#create-messages-declaration]

To enable [type-safe message arguments](/docs/workflows/typescript#messages-arguments), you can point the `createMessagesDeclaration` option to a sample messages file in order to create a strict declaration file for it.

```tsx filename="next.config.ts"
const withNextIntl = createNextIntlPlugin({
  experimental: {
    // Provide the path to the messages that you're using in `AppConfig`
    createMessagesDeclaration: './messages/en.json'
  }
  // ...
});
```

See [TypeScript augmentation](/docs/workflows/typescript) to learn more about this.

**Note:** This is not necessary when using [`useExtracted`](/docs/usage/extraction).

### `extract` [#extract]

This enables the usage of [`useExtracted`](/docs/usage/extraction) to automatically extract messages from source files.

```tsx
const withNextIntl = createNextIntlPlugin({
  experimental: {
    extract: {
      // Defines which locale to extract to
      sourceLocale: 'en'
    }
    // ...
  }
});
```

**Note:** The `extract` option should be used together with [`messages`](#messages) and [`srcPath`](#src-path).

### `messages` [#messages]

This defines where and how messages for locales should be stored.

```tsx
const withNextIntl = createNextIntlPlugin({
  experimental: {
    messages: {
      // Relative path to the directory
      path: './messages',

      // Automatically detects locales based on `path`
      locales: 'infer',

      // Either 'json' or 'po'
      format: 'json'
    }
    // ...
  }
});
```

If you want to specify the locales explicitly, you can provide an array for `locales`:

```tsx
locales: ['en', 'de'];
```

Configuring `experimental.messages` will also set up a Turbo- or Webpack loader that will ensure loaded messages can be imported as plain JavaScript objects (see [formatters](/docs/usage/extraction#formatters)).

**Note:** The `messages` option should be used together with [`extract`](#extract) and [`srcPath`](#src-path).

### `srcPath` [#src-path]

This defines the source path where messages should be extracted from.

```tsx
const withNextIntl = createNextIntlPlugin({
  experimental: {
    srcPath: './src'
    // ...
  }
});
```

If your project is split into multiple folders, you can provide an array of paths:

```tsx
// Not using a `src` folder
srcPath: './',
```

```tsx
// Monorepo with multiple packages
srcPath: ['./src', '../ui'],
```

```tsx
// External dependency on a package
srcPath: ['./src', './node_modules/@acme/components'],
```

Note that the directories `node_modules`, `.next` and `.git` are automatically excluded from extraction, except for if they appear explicitly in the `srcPath` array.

If you want to provide messages along with your package, you can also extract them [manually](/docs/usage/extraction#manual).

**Note:** The `srcPath` option should be used together with [`extract`](#extract) and [`messages`](#messages).
